---
type: integration
title: '@astrojs/partytown'
description: 了解如何在你的 Astro 项目中使用 @astrojs/partytown 集成。
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/partytown/'
category: other
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';

此 **[Astro 集成][astro-integration]** 允许你在 Astro 项目中启用 [Partytown](https://partytown.builder.io/)。

## 为什么是 Astro Partytown

Partytown 是一个延迟加载的库，可以帮助将资源密集型脚本转移到 [web worker](https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Workers_API) 中，并且从 [主线程](https://developer.mozilla.org/zh-CN/docs/Glossary/Main_thread) 中移除。

如果你使用第三方脚本进行分析或广告等操作，Partytown 是确保它们不会减慢网站速度的绝佳方法。

Astro Partytown 集成会为你安装 Partytown 并确保它在所有页面上启用。

## 安装

Astro 包含了一个 `astro add` 命令，用于自动设置官方集成。如果你愿意，可以改为[手动安装集成](#手动安装)。

在新的终端窗口中运行以下其中一个命令。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add partytown
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add partytown
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add partytown
  ```
  </Fragment>
</PackageManagerTabs>

如果你遇到任何问题，[请随时在 GitHub 上向我们报告](https://github.com/withastro/astro/issues)并尝试下面的手动安装步骤。

### 手动安装

首先，安装 `@astrojs/partytown` 包:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/partytown
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/partytown
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/partytown
  ```
  </Fragment>
</PackageManagerTabs>

然后，使用 `integrations` 属性将集成应用到你的 `astro.config.*` 文件中：

```js title="astro.config.mjs" ins={2} ins="partytown()"
import { defineConfig } from 'astro/config';
import partytown from '@astrojs/partytown';
export default defineConfig({
  // ...
  integrations: [partytown()],
});
```

## 使用

Partytown 应该可以零配置使用。如果你网站上已经有现成的第三方脚本，试试添加 `type="text/partytown"` 属性：

```html ins="type="text/partytown""
<script type="text/partytown" src="fancy-analytics.js"></script>
```

如果你打开 [浏览器开发者工具](https://developer.chrome.com/docs/devtools/open/) 的“网络 Network”标签，你应该可以看到 `partytown` 代理拦截了这个请求。

## 配置

要配置此集成，请将一个 'config' 对象传递给 `astro.config.mjs` 中的 `partytown()` 函数调用。

```js title="astro.config.mjs" {5-7}
export default defineConfig({
  // ...
  integrations: [
    partytown({
      config: {
        // 配置项在这
      },
    }),
  ],
});
```

这与 [Partytown 配置对象](https://partytown.builder.io/configuration) 相对应。

### config.debug

Partytown 自带一个 `debug` 模式；通过向 `config.debug` 传入 `true` 或 `false` 来启用或禁用它。如果启用了[`debug` 模式](https://partytown.builder.io/debugging)，它会向浏览器控制台输出详细的日志。

如果不设置此选项，在 [dev](/zh-cn/reference/cli-reference/#astro-dev) 或 [preview](/zh-cn/reference/cli-reference/#astro-preview) 模式下，`debug` 模式默认启用。

```js title="astro.config.mjs" {6}
export default defineConfig({
  // ...
  integrations: [
    partytown({
      // 示例：禁用调试模式。
      config: { debug: false },
    }),
  ],
});
```

### config.forward

第三方脚本通常会向 `window` 对象添加变量，以便你可以在整个站点与它们通信。但是当一个脚本在 web worker 中加载时，它无法访问全局的 `window` 对象。

为了解决这个问题，Partytown 可以“打补丁”变量到全局 window 对象并将它们转发到适当的脚本。

你可以使用 `config.forward` 选项指定要转发的变量。[在 Partytown 的文档中了解更多信息。](https://partytown.builder.io/forwarding-events)

```js title="astro.config.mjs" {7}
export default defineConfig({
  // ...
  integrations: [
    partytown({
      // 示例：将 dataLayer.push 作为 forwarding-event 添加。
      config: {
        forward: ['dataLayer.push'],
      },
    }),
  ],
});
```

## 例子

* [在 GitHub 上浏览使用 Astro Partytown 的项目](https://github.com/search?q=%22%40astrojs%2Fpartytown%22+path%3A**%2Fpackage.json\&type=code) 来获取更多例子！

[astro-integration]: /zh-cn/guides/integrations-guide/
